'\" t
.\"     Title: IPSEC_AUTO
.\"    Author: Paul Wouters
.\" Generator: DocBook XSL Stylesheets v1.77.1 <http://docbook.sf.net/>
.\"      Date: 12/16/2012
.\"    Manual: Executable programs
.\"    Source: libreswan
.\"  Language: English
.\"
.TH "IPSEC_AUTO" "8" "12/16/2012" "libreswan" "Executable programs"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
ipsec_auto \- control automatically\-keyed IPsec connections
.SH "SYNOPSIS"
.HP \w'\fBipsec\fR\ 'u
\fBipsec\fR \fIauto\fR [\-\-show] [\-\-showonly] [\-\-asynchronous]
.br
[\-\-config\ \fIconfigfile\fR] [\-\-verbose] \fIoperation\ connection\fR
.br

.HP \w'\fBipsec\fR\ 'u
\fBipsec\fR \fIauto\fR [\-\-show] [\-\-showonly] [\-\-asynchronous]
.br
[\-\-config\ \fIconfigfile\fR] [\-\-verbose] \fIoperation\ connection\fR
.br

.SH "EXAMPLES"
.HP \w'\fBipsec\fR\ 'u
\fBipsec\fR \fIauto\fR {\ \-\-add\ |\ \-\-delete\ |\ \-\-replace\ |\ \-\-up\ |\ \-\-down\ } \fIconnection\fR
.HP \w'\fBipsec\fR\ 'u
\fBipsec\fR \fIauto\fR {\ \-\-status\ |\ \-\-ready\ } \fIconnection\fR
.HP \w'\fBipsec\fR\ 'u
\fBipsec\fR \fIauto\fR {\ \-\-route\ |\ \-\-unroute\ } \fIconnection\fR
.HP \w'\fBipsec\fR\ 'u
\fBipsec\fR \fIauto\fR [\-\-utc] [\-\-listall\ |\ \-\-rereadall] [\-\-rereadsecrets] [\-\-listcerts] [\-\-listpubkeys] [\-\-checkpubkeys] [\-\-listcacerts\ |\ \-\-rereadcacerts] [\-\-listcrls\ |\ \-\-rereadcrls] [\-\-listacerts\ |\ \-\-rereadacerts] [\-\-listaacerts\ |\ \-\-rereadaacerts] [\-\-listgroups\ |\ \-\-rereadgroups]
.SH "DESCRIPTION"
.PP
\fIAuto\fR
manipulates automatically\-keyed Libreswan IPsec connections, setting them up and shutting them down based on the information in the IPsec configuration file\&. In the normal usage,
\fIconnection\fR
is the name of a connection specification in the configuration file;
\fIoperation\fR
is
\fB\-\-add\fR,
\fB\-\-delete\fR,
\fB\-\-replace\fR,
\fB\-\-up\fR,
\fB\-\-down\fR,
\fB\-\-route\fR, or
\fB\-\-unroute\fR\&. The
\fB\-\-ready\fR,
\fB\-\-rereadsecrets\fR,
\fB\-\-rereadgroups\fR, and
\fB\-\-status\fR
\fIoperations\fR
do not take a connection name\&.
\fIAuto\fR
generates suitable commands and feeds them to a shell for execution\&.
.PP
The
\fB\-\-add\fR
operation adds a connection specification to the internal database within
\fIpluto\fR; it will fail if
\fIpluto\fR
already has a specification by that name\&. The
\fB\-\-delete\fR
operation deletes a connection specification from
\fIpluto\fR\*(Aqs internal database (also tearing down any connections based on it); it will fail if the specification does not exist\&. The
\fB\-\-replace\fR
operation is equivalent to
\fB\-\-delete\fR
(if there is already a specification by the given name) followed by
\fB\-\-add\fR, and is a convenience for updating
\fIpluto\fR\*(Aqs internal specification to match an external one\&. (Note that a
\fB\-\-rereadsecrets\fR
may also be needed\&.) The
\fB\-\-rereadgroups\fR
operation causes any changes to the policy group files to take effect (this is currently a synonym for
\fB\-\-ready\fR, but that may change)\&. None of the other operations alters the internal database\&.
.PP
The
\fB\-\-up\fR
operation asks
\fIpluto\fR
to establish a connection based on an entry in its internal database\&. The
\fB\-\-down\fR
operation tells
\fIpluto\fR
to tear down such a connection\&.
.PP
Normally,
\fIpluto\fR
establishes a route to the destination specified for a connection as part of the
\fB\-\-up\fR
operation\&. However, the route and only the route can be established with the
\fB\-\-route\fR
operation\&. Until and unless an actual connection is established, this discards any packets sent there, which may be preferable to having them sent elsewhere based on a more general route (e\&.g\&., a default route)\&.
.PP
Normally,
\fIpluto\fR\*(Aqs route to a destination remains in place when a
\fB\-\-down\fR
operation is used to take the connection down (or if connection setup, or later automatic rekeying, fails)\&. This permits establishing a new connection (perhaps using a different specification; the route is altered as necessary) without having a \(lqwindow\(rq in which packets might go elsewhere based on a more general route\&. Such a route can be removed using the
\fB\-\-unroute\fR
operation (and is implicitly removed by
\fB\-\-delete\fR)\&.
.PP
The
\fB\-\-ready\fR
operation tells
\fIpluto\fR
to listen for connection\-setup requests from other hosts\&. Doing an
\fB\-\-up\fR
operation before doing
\fB\-\-ready\fR
on both ends is futile and will not work, although this is now automated as part of IPsec startup and should not normally be an issue\&.
.PP
The
\fB\-\-status\fR
operation asks
\fIpluto\fR
for current connection status\&. The output format is ad\-hoc and likely to change\&.
.PP
The
\fB\-\-rereadsecrets\fR
operation tells
\fIpluto\fR
to re\-read the
/etc/ipsec\&.secrets
secret\-keys file, which it normally reads only at startup time\&. (This is currently a synonym for
\fB\-\-ready\fR, but that may change\&.)
.PP
The
\fB\-\-rereadsecrets\fR
operation tells pluto to re\-read the /etc/ipsec\&.secrets secret\-keys file, which it normally reads only at startup time\&. (This is currently a synonym for
\fB\-\-ready,\fR
but that may change\&.)
.PP
The
\fB\-\-rereadcacerts\fR
operation reads all certificate files contained in the /etc/ipsec\&.d/cacerts directory and adds them to pluto\(^as list of Certification Authority (CA) certificates\&.
.PP
The
\fB\-\-rereadaacerts\fR
operation reads all certificate files contained in the /etc/ipsec\&.d/aacerts directory and adds them to pluto\(^as list of Authorization Authority (AA) certificates\&.
.PP
The
\fB\-\-rereadacerts\fR
operation reads all certificate files contained in the /etc/ipsec\&.d/acerts directory and adds them to pluto\(^as list of attribute certificates\&.
.PP
The
\fB\-\-rereadcrls\fR
operation reads all certificate revocation list (CRL) files contained in the /etc/ipsec\&.d/crls directory and adds them to pluto\(^as list of CRLs\&.
.PP
The
\fB\-\-rereadall\fR
operation is equivalent to the execution of \-\-rereadse\- crets,
\fB\-\-rereadcacerts,\fR
\-\-rereadaacerts, \-\-rereadac\- erts, and \-\-rereadcrls\&.
.PP
The
\fB\-\-listpubkeys\fR
operation lists all RSA public keys either received from peers via the IKE protocol embedded in authenticated certificate payloads or loaded locally using the rightcert / leftcert or rightr\- sasigkey / leftrsasigkey parameters in ipsec\&.conf(5)\&.
.PP
The
\fB\-\-listcerts\fR
operation lists all X\&.509 certificates loaded locally using the rightcert and leftcert parameters in ipsec\&.conf(5)\&.
.PP
The
\fB\-\-checkpubkeys\fR
operation lists all loaded X\&.509 certificates which are about to expire or have been expired\&.
.PP
The
\fB\-\-listcacerts\fR
operation lists all X\&.509 CA certificates either loaded locally from the /etc/ipsec\&.d/cacerts directory or received in PKCS#7\-wrapped certificate payloads via the IKE protocol\&.
.PP
The
\fB\-\-listaacerts\fR
operation lists all X\&.509 AA certificates loaded locally from the /etc/ipsec\&.d/aacerts directory\&.
.PP
The
\fB\-\-listacerts\fR
operation lists all X\&.509 attribute certificates loaded locally from the /etc/ipsec\&.d/acerts directory\&.
.PP
The
\fB\-\-listgropus\fR
operation lists all groups that are either used in connection definitions in ipsec\&.conf(5) or are embedded in loaded X\&.509 attributes certificates\&.
.PP
The
\fB\-\-listcainfos\fR
operation lists the certification authority informa\- tion specified in the ca sections of ipsec\&.conf(5)\&.
.PP
The
\fB\-\-listcrls\fR
operation lists all Certificate Revocation Lists (CRLs) either loaded locally from the /etc/ipsec\&.d/crls directory or fetched dynamically from an HTTP or LDAP server\&.
.PP
The
\fB\-\-listall\fR
operation is equivalent to the execution of \-\-listpubkeys, \-\-listcerts, \-\-listcacerts, \-\-listaacerts, \-\-listoc\- spcerts, \-\-listacerts, \-\-listgroups, \-\-listcainfos, \-\-listcrls\&.
.PP
The
\fB\-\-showonly\fR
option causes
\fIauto\fR
to show the commands it would run, on standard output, and not run them\&.
.PP
The
\fB\-\-asynchronous\fR
option, applicable only to the
\fBup\fR
operation, tells
\fIpluto\fR
to attempt to establish the connection, but does not delay to report results\&. This is especially useful to start multiple connections in parallel when network links are slow\&.
.PP
The
\fB\-\-verbose\fR
option instructs
\fIauto\fR
to pass through all output from
\fBipsec_whack\fR(8), including log output that is normally filtered out as uninteresting\&.
.PP
The
\fB\-\-show\fR
option turns on the
\fB\-x\fR
option of the shell used to execute the commands, so each command is shown as it is executed\&.
.PP
The
\fB\-\-config\fR
option specifies a non\-standard location for the IPsec configuration file (default
/etc/ipsec\&.conf)\&.
.PP
See
\fBipsec.conf\fR(5)
for details of the configuration file\&.
.SH "FILES"
.PP

.sp
.if n \{\
.RS 4
.\}
.nf
/etc/ipsec\&.conf			default IPSEC configuration file
/etc/ipsec\&.d/			X\&.509 and Opportunistic Encryption files
/var/run/pluto/pluto\&.ctl	Pluto command socket
.fi
.if n \{\
.RE
.\}
.sp
.SH "SEE ALSO"
.PP
\fBipsec.conf\fR(5),
\fBipsec\fR(8),
\fBipsec_pluto\fR(8),
\fBipsec_whack\fR(8),
\fBipsec_manual\fR(8)
.SH "HISTORY"
.PP
Originally written for the FreeS/WAN project <\m[blue]\fBhttp://www\&.freeswan\&.org\fR\m[]> by Henry Spencer\&.
.SH "BUGS"
.PP
Although an
\fB\-\-up\fR
operation does connection setup on both ends,
\fB\-\-down\fR
tears only one end of the connection down (although the orphaned end will eventually time out)\&.
.PP
There is no support for
\fBpassthrough\fR
connections\&.
.PP
A connection description which uses
\fB%defaultroute\fR
for one of its
\fBnexthop\fR
parameters but not the other may be falsely rejected as erroneous in some circumstances\&.
.PP
The exit status of
\fB\-\-showonly\fR
does not always reflect errors discovered during processing of the request\&. (This is fine for human inspection, but not so good for use in scripts\&.)
.SH "AUTHOR"
.PP
\fBPaul Wouters\fR
.RS 4
placeholder to suppress warning
.RE
